Skip to content

feat(package_info_plus): add opt-in compile-time package info accessor#3874

Open
Ortes wants to merge 2 commits into
fluttercommunity:mainfrom
Fullphysio:package-info-compile-time-version
Open

feat(package_info_plus): add opt-in compile-time package info accessor#3874
Ortes wants to merge 2 commits into
fluttercommunity:mainfrom
Fullphysio:package-info-compile-time-version

Conversation

@Ortes

@Ortes Ortes commented Jun 12, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Description

On the web, PackageInfo.fromPlatform() resolves the version by fetching version.json from the server at runtime (with a cache buster). That file reflects whatever is currently deployed — not the bundle actually executing in the browser. The two states routinely diverge:

This makes the reported version actively misleading rather than merely missing — and the version is the whole point of the plugin. Its two canonical uses, showing the running version and checking whether an update is needed, are both defeated when the value is the server's. An update gate built on it can never fire for the very users it targets, since stale clients self-report as up to date.

This PR

Adds a small opt-in library, package_info_plus_environment.dart, exposing PackageInfoEnvironment.packageInfo:

import 'package:package_info_plus/package_info_plus_environment.dart';

final info = await PackageInfoEnvironment.packageInfo;
  • Web — returns a PackageInfo built from compile-time PACKAGE_INFO_PLUS_* defines (flutter build web --dart-define=PACKAGE_INFO_PLUS_VERSION=1.2.3 ...). These are embedded in the running bundle and cannot diverge from it. A web build that omits PACKAGE_INFO_PLUS_VERSION fails to compile (a kIsWeb-conditional const assert), so a misleading version can never ship silently.
  • All other platforms — delegates to PackageInfo.fromPlatform(), which reads the installed binary and is already reliable. The defines are not required there.

Design choices that keep this safe and non-breaking:

  • PackageInfo.fromPlatform() is untouched. No behavior change for existing users.
  • Opt-in via a separate library that the package barrel does not export. The compile-time guard is evaluated per compiled library, so it only affects code that explicitly imports package_info_plus_environment.dart. Apps that don't opt in are completely unaffected — no new build requirement is imposed package-wide.
  • Cross-platform by construction (single accessor, platform-appropriate source), per the contributing guide's rule against single-platform features.
  • The framework-side requests to expose the build version were declined ("Static" versioning in flutter web flutter/flutter#149725, [WEB] Web Cache invalidation based on pubspec.yaml version flutter/flutter#149031), so a plugin-level opt-in seems to be the only avenue available to users today. If Flutter later injects build name/number defines, this accessor can read them with no API change.

flutter analyze is clean and the existing + new tests pass. The web compile-time enforcement is verified by a compilation test (a web build without the define does not compile) rather than a runtime test.

Related Issues

Checklist

  • I read the Contributor Guide and followed the process outlined there for submitting PRs.
  • I titled the PR using Conventional Commits.
  • I did not modify the CHANGELOG.md nor the plugin version in pubspec.yaml files.
  • All existing and new tests are passing.
  • The analyzer (flutter analyze) does not report any problems on my PR.

Breaking Change

  • Yes, this is a breaking change.
  • No, this is not a breaking change.

@Ortes
feat(package_info_plus): add opt-in compile-time package info accessor
13e02bd 
Adds an opt-in library, package_info_plus_environment.dart, exposing
PackageInfoEnvironment.packageInfo. It returns the *running* app's
PackageInfo: on web from compile-time PACKAGE_INFO_PLUS_* dart-defines,
on every other platform by delegating to PackageInfo.fromPlatform().

On web there is no reliable runtime source for the running version:
version.json is fetched from the server, so it reflects the deployed
version rather than the executing (possibly cached) bundle, and the fetch
can fail entirely (offline, CORS, hosting rewrites). The compile-time
constants are embedded in the bundle and cannot diverge from it. A web
build that omits PACKAGE_INFO_PLUS_VERSION fails to compile, so a
misleading version can never ship silently. Native builds are unaffected.

PackageInfo.fromPlatform() is unchanged and the new library is not
exported by the package barrel, so this is purely additive and opt-in.

Related: fluttercommunity#2675, fluttercommunity#225, fluttercommunity#456, flutter/flutter#149031.
@Ortes Ortes force-pushed the package-info-compile-time-version branch from e31c344 to 13e02bd Compare June 12, 2026 11:22
@Ortes Ortes changed the title feat(package_info_plus): support compile-time package info via dart-defines feat(package_info_plus): add opt-in compile-time package info accessor Jun 12, 2026
This was referenced Jun 12, 2026
Open
Open
@Ortes

Ortes commented Jun 12, 2026

Copy link
Copy Markdown
Contributor Author

Re: CI status — the red checks here are pre-existing infrastructure failures, not regressions from this PR. Evidence:

The jobs that actually exercise this change all pass:

  • Dart Analyzer ✓ · web_example_build ✓ · android_integration_test (24) ✓ · linux/windows build + integration ✓

The failing jobs fail identically on main and on every recent unrelated PR:

  • all_plugins analyze/pub-check fails on a sensors_plus invalid_annotation_target warning (unrelated package) — red on every PR including ones targeting main.
  • macos_example_build / ios_example_build: Plugin package_info_plus has a Package.swift for macos but is missing a dependency on FlutterFramework + CocoaPods xcfilelist errors — Xcode/SPM toolchain drift on the runners.
  • android_integration_test (shards 29/32/36): Timeout waiting for emulator to boot — emulator flake; shard 24 booted and passed.
  • web_integration_test: AppConnectionException from chromedriver, then a 30-min hang until cancel — driver flake, not a compile error (the web example compiles and launches in the log).

The last ~6 package_info_plus PRs (kotlin-dsl migration, ubuntu-24.04 migration, win32 relax, built-in-kotlin) are all red for the same reasons.

This change is purely additive: a new, non-exported package_info_plus_environment.dart library. It doesn't touch any existing code path, and the barrel (package_info_plus.dart) is unchanged — so existing consumers and the example's web build are unaffected. Happy to rebase once the CI infra is sorted.

@Ortes
feat(package_info_plus): recognize tool-provided version defines as f…
fbb9e09 
…allbacks

PackageInfoEnvironment now resolves the web version from, in order:
PACKAGE_INFO_PLUS_VERSION (explicit), FLUTTER_BUILD_NAME
(flutter/flutter#187935, injected by flutter_tools like
FLUTTER_APP_FLAVOR), and dart.package.version (dart-lang/sdk#38855).
Once either upstream proposal lands, apps need no configuration at all.
This was referenced Jun 12, 2026
Open
Open
Open
Closed
@Ortes

Ortes commented Jun 12, 2026

Copy link
Copy Markdown
Contributor Author

Forward-compatibility note. This PR now also recognizes tool-provided version defines as fallbacks, so apps will need no configuration at all once their build front-end injects the version itself:

Resolution order is: explicit PACKAGE_INFO_PLUS_VERSION → FLUTTER_BUILD_NAME → dart.package.version. The two upstream proposals and this PR are deliberately complementary: at least one of them needs to exist for PackageInfo to stop silently reporting the wrong version on web, and whichever lands first makes this plugin correct-by-default there.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

[Bug]: [package_info_plus] Web: Version info returns next version in server

1 participant

@Ortes